/*
 * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang.reflect;

/**
 * 当代理实例上的方法调用的调用处理器的 {@link InvocationHandler#invoke invoke} 方法
 * 抛出受检异常（不能赋值给 {@code RuntimeException} 或 {@code Error} 的 {@code Throwable}），
 * 且该异常不能赋值给在代理实例上调用并分派给调用处理器的方法的 {@code throws} 子句中
 * 声明的任何异常类型时抛出。
 *
 * <p>{@code UndeclaredThrowableException} 实例包含由调用处理器抛出的未声明受检异常，
 * 可以通过 {@code getUndeclaredThrowable()} 方法检索。
 * {@code UndeclaredThrowableException} 扩展了 {@code RuntimeException}，
 * 因此它是一个包装受检异常的非受检异常。
 *
 * <p>从 1.4 版本开始，此异常已被改造以符合通用异常链机制。
 * 可能在构造时提供并通过 {@link #getUndeclaredThrowable()} 方法访问的
 * "由调用处理器抛出的未声明受检异常"现在被称为<i>原因</i>，
 * 可以通过 {@link Throwable#getCause()} 方法以及前述的"遗留方法"访问。
 *
 * @author      Peter Jones
 * @see         InvocationHandler
 * @since       1.3
 */
public class UndeclaredThrowableException extends RuntimeException {
    static final long serialVersionUID = 330127114055056639L;

    /**
     * 抛出的未声明受检异常
     * @serial
     */
    private Throwable undeclaredThrowable;

    /**
     * 使用指定的 {@code Throwable} 构造 {@code UndeclaredThrowableException}。
     *
     * @param   undeclaredThrowable 抛出的未声明受检异常
     */
    public UndeclaredThrowableException(Throwable undeclaredThrowable) {
        super((Throwable) null);  // Disallow initCause
        this.undeclaredThrowable = undeclaredThrowable;
    }

    /**
     * 使用指定的 {@code Throwable} 和详细消息构造 {@code UndeclaredThrowableException}。
     *
     * @param   undeclaredThrowable 抛出的未声明受检异常
     * @param   s 详细消息
     */
    public UndeclaredThrowableException(Throwable undeclaredThrowable,
                                        String s)
    {
        super(s, null);  // Disallow initCause
        this.undeclaredThrowable = undeclaredThrowable;
    }

    /**
     * 返回包装在此 {@code UndeclaredThrowableException} 中的 {@code Throwable} 实例，
     * 可能为 {@code null}。
     *
     * <p>此方法早于通用异常链机制。
     * {@link Throwable#getCause()} 方法现在是获取此信息的首选方式。
     *
     * @return 抛出的未声明受检异常
     */
    public Throwable getUndeclaredThrowable() {
        return undeclaredThrowable;
    }

    /**
     * 返回此异常的原因（包装在此 {@code UndeclaredThrowableException} 中的
     * {@code Throwable} 实例，可能为 {@code null}）。
     *
     * @return  此异常的原因
     * @since   1.4
     */
    public Throwable getCause() {
        return undeclaredThrowable;
    }
}
